supports-color

What is supports-color?

The supports-color npm package is used to detect whether a terminal supports color and, if so, which kinds of color. It can be used to tailor output to the terminal's capabilities, avoiding the use of color when it's not supported and enabling it when possible. This can help improve the readability and aesthetics of command-line tool output.

What are supports-color's main functionalities?

Detecting Color Support

This feature allows you to check if the terminal supports color, and if so, what level of color support it has (basic colors, 256 colors, or 16 million colors).

const supportsColor = require('supports-color');
if (supportsColor.stdout) {
  console.log('Terminal stdout supports color');
}
if (supportsColor.stdout.has256) {
  console.log('Terminal stdout supports 256 colors');
}
if (supportsColor.stderr.has16m) {
  console.log('Terminal stderr supports 16 million colors (truecolor)');
}

Forcing Color Support

This feature allows you to force color support in the terminal. This can be useful for testing or when running in environments where color support is not detected correctly.

const supportsColor = require('supports-color');
process.env.FORCE_COLOR = '1';
supportsColor.stdout.level = 1;
console.log('Forced color support level to basic colors');

Other packages similar to supports-color

chalk

Chalk is a popular npm package that allows you to style and colorize text in the terminal. It is more feature-rich than supports-color, providing an easy-to-use API for applying styles, but it also uses supports-color internally to determine color support.

ansi-colors

ansi-colors is another npm package for coloring terminal text. It focuses on being lightweight and has no dependencies. It offers a similar API to chalk but does not have the same level of abstraction or convenience methods.

cli-color

cli-color is an npm package that provides a function-based API for styling terminal text. It offers color support detection as well as a wide range of text formatting options. It is more comprehensive than supports-color but also more complex to use.

README

supports-color

Detect whether a terminal supports color

Install

$ npm install supports-color

Usage

const supportsColor = require('supports-color');

if (supportsColor.stdout) {
	console.log('Terminal stdout supports color');
}

if (supportsColor.stdout.has256) {
	console.log('Terminal stdout supports 256 colors');
}

if (supportsColor.stderr.has16m) {
	console.log('Terminal stderr supports 16 million colors (truecolor)');
}

API

Returns an Object with a stdout and stderr property for testing either streams. Each property is an Object, or false if color is not supported.

The stdout/stderr objects specifies a level of support for color through a .level property and a corresponding flag:

• .level = 1 and .hasBasic = true: Basic color support (16 colors)
• .level = 2 and .has256 = true: 256 color support
• .level = 3 and .has16m = true: Truecolor support (16 million colors)

Info

It obeys the --color and --no-color CLI flags.

Can be overridden by the user with the flags --color and --no-color. For situations where using --color is not possible, add the environment variable FORCE_COLOR=1 to forcefully enable color or FORCE_COLOR=0 to forcefully disable. The use of FORCE_COLOR overrides all other color support checks.

Explicit 256/Truecolor mode can be enabled using the --color=256 and --color=16m flags, respectively.

Related

• supports-color-cli - CLI for this module
• chalk - Terminal string styling done right

Maintainers

• Sindre Sorhus
• Josh Junon

License

MIT